Release notes

2024r8

PUT /commercialBreakDuration call in commercial API

Using the commercial API, it is not possible to update the duration of time allocations with the POST /commercialPlaylist call. Even if it would be, the interstitial integration synchronization does not update time allocation durations either because the existing calls update schedule inbox objects that do not directly affect time allocations.

However, previously, if the external system already knew the time allocations would be longer or shorter than defined in the schedule, it could not send this update to Mediagenix Base platform.

Therefore, from this version, the PUT /commercialBreakDuration call has been added to the commercial API. It can update the duration of multiple time allocations on one day, channel and schedule version.

The call will map the time allocations on either the block label using the breakId attribute, or the external block label using the externalBreakId attribute. Only the one defined on the interstitial integration definition has to be provided.

It is only possible to update time allocations that have transmission events and have the All scheduled by interstitial integration property set to Yes.

An example of the body:

{
  "channelId": "MGX",
  "startDate": "2024-09-01",
  "scheduleVersion": "Active",
  "timeAllocations": [
    {
      "breakId": "00001010",
      "externalBreakId": "010101010",
      "duration": "00:05:01"
    },
    {
      "breakId": "00000101",
      "externalBreakId": "00002222,
      "duration": "00:03:14"
    }
  ]
}

API developers

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

At line 164, the /commercialBreakDuration path was added.
At line 856, the TimeAllocationForBreakDuration schema was added.
At other lines, some descriptions were updated.

For easier viewing, the YAMLs can also be compared here: https://www.textcompare.org/yaml

Predicted ratings in business API

In version 2024r8, predicted ratings calculation was introduced.

Once the predicted ratings are calculated and the actual ratings are imported, the results can be used in the commercial API.

In the commercial API, the GET /breakSchedule call returns the break schedule for one complete broadcast day for all time allocations that are part of a published interstitial integration definition.

In version 2022r7, the predictedRatings array returned the predicted TRP ratings of a time allocation. (See 2022r7) These could be entered in the trailer grid using the Edit predicted ratings… command.

From this version, the predictedRatings array will return the final predicted ratings of a time allocation, which can be seen in the predicted ratings navigator.

An example of the response of the GET /breakSchedule call after generating predicted ratings:

        {
            "transmissionId": "9501319722",
            "startTime": "11:00:00",
            "startTimeUTC": "10:00:00",
            "announcedStartTime": "11:00",
            "lockedStartTime": false,
            "duration": "00:34:00",
            ...
            "contractNumber": null,
            "timeAllocations": [
                {
                    "breakId": null,
                    "externalBreakId": null,
                    "startTime": "10:58:00",
                    "duration": "00:01:00",
                    "type": "trailer",
                    "position": "Start",
                    "startTimeUTC": "09:58:00",
                    "readOnly": true,
                    "title": "I MAY DESTROY YOU - Social Media Is a Great Way to Connect -  - Auto promotion",
                    "sequenceNumber": 1,
                    "regional": false,
                    "masterBreakId": null,
                    "predictedRatings": [
                        {
                            "rating": 0.0952,
                            "targetGroup": "Teens"
                        },
                        {
                            "rating": 3.6560,
                            "targetGroup": "Adults"
                        },
                        {
                            "rating": 6.7509,
                            "targetGroup": "Kids"
                        },
                        {
                            "rating": 2.0556,
                            "targetGroup": "60+"
                        }
                    ]
                },

2024r7

Update media assets of commercials using commercial API

The commercial API supports interstitial integration between Mediagenix Base platform and an external system (RN-4359).

Previously, the POST /commercialPlaylist, POST /commercial and PUT /commercialBreak calls allowed to create media assets, but were not be able to update it. This was because it was assumed that the MAM system became the owner after creation in the Mediagenix Base platform.

For example, for the following POST /commercial call body:

{
  "duration": "00:01:00",
  "interstitialId": "9501012904",
  "title": "The Eras Tour",
  "mediaAssets": [
    {
      "mediaAssetId": "9501012906",
      "frameRate": "25fps",
      "label": "TET023072024",
      "preferred": false,
      "kind": "ANTENNE"
    }
  ]
}

It was checked if the media asset referenced in the mediaAssetId already existed:

If so, the media asset information in the payload was ignored and the BAPI service would log: Media asset information was ignored. The commercial API can only create media assets.
If it did not exist, the media asset was created.

However, for some customers, the commercial integration system should be allowed to update media assets. Therefore, from this version, the message above will not appear in the service anymore and a media asset can be updated using the mediaAssets array in the body of the POST /commercialPlaylist, POST /commercial and PUT /commercialBreak calls.

The YAML did not change for this adjustment.

2024r3

Time allocation and transmission event remarks in commercial API
Ratings in POST /commercial call of commercial API

Time allocation and transmission event remarks in commercial API

The commercial API enables interstitial integration using the business API.

The POST /commercialPlaylist and PUT /commercialBreak calls are used to create and update the interstitial blocks and clips that will be synchronised.

From this version, the remarks on time allocations and transmission events in WHATS'ON can be synchronised from an external system using interstitial integration (RN-6314).

To support an update to the remarks also from the API, the remarks attribute has been added to the timeAllocations array and events array of the POST /commercialPlaylist and PUT /commercialBreak calls.

An example of the POST /commercialPlaylist body:

{
  "channelId": "MGX",
  "startDate": "2024-05-01",
  "definitionId": "Comm",
    "timeAllocations": [
    {
      "breakId": "000018",
      "startTime": "05:56:00",
      "startTimeUTC": "03:56:00",
      "type": "commercial",
      "remarks": "filled by API",
      "events": [
        {
          "spotId": "INTINTEG01",
          "eventId": "INTINTEG01",
          "duration": "00:15:00",
          "sequenceNumber": 1,
          "remarks": "filled by API",
          "commercial": {
            "interstitialId": "INTINTEG01",
            "identification": "INTINTEG01",
            "duration": "00:00:20",
            "title": "MARINE TRAFFIC",
          }
        }
      ]
    }
  ]
}

When the Use external remarks column on the interstitial integration definition (RN-6314) is set to No, and the remarks are changed using the API, the remarks on the interstitial blocks or interstitial clips are still updated but they will not trigger a change for synchronisation with the time allocations and transmission events.

API developers

For API developers, the following has changed in the YAML:

A note has been added at line 114 to the description of the /commercialBreak put call.
At line 827, the following is added to the TimeAllocationForPlaylist schema:
remarks:
type: string
description: Remarks for the time allocation
At line 854, the following is added to the Event schema:
remarks:
type: string
description: Remarks for the time allocation
At line 860, a different schema is referenced.
At line 918, a new CommercialForPlaylist schema is added.

For easier viewing, the YAMLs can also be compared here: https://www.textcompare.org/yaml

Ratings in POST /commercial call of commercial API

It is possible to create commercials and their media assets using the POST /commercial call of the commercial API.

From this version, it is possible to add parental ratings when creating media assets. For this, the ratings array has been added to the mediaAssets part of the POST /commercial call.

The array contains the following attributes:

regulator:
Maps to the Regulator field in the PARENTAL RATINGS PER REGULATOR list on the Parental rating tab on media assets in WHATS'ON Base. The field takes its values from the WOnRegulator drop-down list.
rating:
Maps to the Parental rating field, with values from the WOnProgramCertification drop-down list.
reason:
Maps to the Reason text field.
status:
Maps to the Parental rating status field, with values from the WOnProgramCertificationState drop-down list.

An example of the array in the body:

      "ratings": [
        {
          "regulator": "ofcom",
          "rating": "16+",
          "reason": "Explicit",
          "status": "Approved"
        },

The YAML has been updated for this change. It can be retrieved by using the GET /api call.

API developers

For API developers, the following has changed in the YAML:

At line 1015, the ratings array has been added to the MediaAssets schema

For easier viewing, the YAMLs can also be compared here: https://www.textcompare.org/yaml

2022r7

Subtitle in POST and PUT calls of commercial API
POST /clashCodes call in commercial API
Predicted ratings in GET /breakSchedule call of commercial API

Subtitle in POST and PUT calls of commercial API

Commercials have a subtitle that can be used to add additional title information.

From this version, the subtitle attribute can be added to the following calls of the commercial API:

POST /commercialPlaylist
PUT /commercialBreak
POST /commercial

For example:

POST /commercial

{
  "duration": "00:01:00",
  "title": "Dog food",
  "interstitialId": "DF-01",
  "identification": "DF-01",
  "subtitle": "New and improved",
  "advertiser": "Dog food maker",
  "advertiserCode": "DFM"
}

POST /clashCodes call in commercial API

In the commercial API, it was already possible to use a GET call to retrieve all existing clash codes, meaning the values of the WOnProductClashCode drop-down list. These could be used in the POST /commercial call.

Since clash codes are usually owned and created by the airtime sales system, a POST /clashCodes call has now been added to the API with the following body:

{
  "id": "Clash1",
  "description": "Alert",
  "parentId": "DoNotAir"
}

Only the description attribute is mandatory. Since the WOnProductClashCode drop-down list is hierarchical, the parentId can be used to create a subvalue of another value.

Predicted ratings in GET /breakSchedule call of commercial API

The GET /breakSchedule call of the commercial API returns the break schedule for one complete broadcast day (for all time allocations that are part of a certain interstitial integration definition).

Since ratings can be important strategic information while making the break schedule, the predicted ratings of time allocations have now been added to the GET /breakSchedule call.

Each predicted rating consists of a target group and actual rating value.

{
    "channelId": "MgX",
    "startDate": "2022-09-01",
    "scheduleVersion": "Active",
    "dayStatus": null,
    "definitionId": "AutoPromotion",
    "transmissions": [
        {
            "transmissionId": "8065726813",
            "startTime": "06:00:00",
            ...
            "timeAllocations": [
                {
                    "breakId": null,
                    "externalBreakId": "0000001365",
                    "startTime": "05:59:30",
                    "duration": "00:00:30",
                    "type": "trailer",
                     ...
                    "title": "HARRY POTTER AND THE CHAMBER OF SECRETS -  - Auto promotion",
                     ...
                    "predictedRatings": [
                        {
                            "rating": 6,
                            "targetGroup": "Adults"
                        },
                       {
                            "rating": 2,
                            "targetGroup": "Kids"
                       }
                    ]
                },
            ]
        }
    ]
}

2022r1

Notification of push outbox record service

In a previous version, the Push outbox record service was introduced for the interstitial integration and the commercial BAPI (RN-4364). It is used to push interstitial schedule outbox records to the external system automatically (RN-4361).

Previously, the notification that this service sends consisted of:

channelID: API reference of the channel

startDate: Date of the broadcasting day

scheduleVersion: Description of schedule version of the broadcasting day

definitionId: Name of the interstitial integration definition

For example:

{
"channelId": "MGX",
"startDate": "2021-11-23"
"scheduleVersion": "Active",
"definitionId": "Commercial"
}

But since the GET /breakSchedule call of the Commercial API uses different information for these parameters, the notification has been made consistent with that call. From now, the notification will consist of:

channelID: API reference of the channel

startDate: Date of the broadcasting day

scheduleVersion: API reference of schedule version of the broadcasting day

definitionId: API reference of the interstitial integration definition

Fix for empty product code causing empty product information in commercial API

In a previous version, the product code was added to the GET /breakSchedule call of the commercial API.

However, when the break schedule contained a transmission linked to a product that did not have a product code, all product information would incorrectly return null. This was because the product code was used to match the product.

{
    "transmissionId": "7655520813",
    "startTime": "29:00:00",
    "startTimeUTC": "27:00:00",
    "announcedStartTime": "29:00",
    "lockedStartTime": false,
    "duration": "01:38:00",
    "productId": null,
    "parentalRating": null,
    "productType": null,
    "productCode": null,
    "productTitle": null,
    "seriesTitle": null,
    "episodeNumber": null,
    "nature": null,
    "genre": null,
    "clashCodes": null,
    "rerun": true,
    "premiere": false,
    "contractNumber": "1",
    "timeAllocations":
}

From this version, this issue has been fixed and only the product code tag will return null. Now, the product is matched based on OID.

{
    "transmissionId": "5655709813",
    "startTime": "17:00:00",
    "startTimeUTC": "16:00:00",
    "announcedStartTime": "17:00",
    "lockedStartTime": false,
    "duration": "02:20:00",
    "productId": "142205527",
    "parentalRating": null,
    "productType": "program",
    "productCode": null,
    "productTitle": "ALITA: BATTLE ANGEL",
    "seriesTitle": null,
    "episodeNumber": null,
    "nature": "Purchase",
    "genre": "TestCategory2",
    "clashCodes": [],
    "rerun": true,
    "premiere": false,
    "contractNumber": "1",
    "timeAllocations": []
}

2021r2.001

API version: v1.1.0

Additions to commercial integration API

In a previous version, the commercial integration API was introduced. Some additions have been done in that API. These include changes to the YAML so it is best to re-execute the call to retrieve the YAML.

GET dayStatus call

A GET /dayStatus call has been added to the Commercial BAPI, which will retrieve the possible day statuses of the Interstitial integration inbox schedule, mapped to WII_InboxDayStatus drop-down list. These values can then be used in the POST /commercialPlaylist call.

An example of the response:

[
    {
        "id": "Active",
        "name": "Active"
    },
    {
        "id": "Closed",
        "name": "Closed"
    }
]

Product code in GET breakSchedules call

In this version, the attribute productCode has been added to the GET /breakSchedules call. It is returned in the response for all transmissions of the break schedule. When there is no product linked or there is more than one product code, the field will be empty.

{
  "channelId": "MGX",
  "startDate": "2021-10-01",
  "scheduleVersion": "Active",
  "dayStatus": "Active",
  "definitionId": "Commercial",
  "transmissions": [
    {
      "transmissionId": 12345678,
      "startTime": "14:00:00",
      "startTimeUTC": "13:15:00",
      "announcedStartTime": "14:00:00",
      "lockedStartTime": true,
      "duration": "01:30:00",
      "productId": "PROD000012234",
      "productCode": "PROD00001",
      "productType": "Program",
      "productTitle": "BLACK WIDOW"
    ...
    }
  ]
}

Fixes

Previously, when sending a PUT /commercialBreak call with a body that included a time allocation type with an API reference that did not exist (for example "commercia" instead of "commercial"), an incorrect response was returned.

Now, this scenario has been fixed and a response with status code 422 is returned:

{
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2021-06-30T13:26:20Z",
    "concept": "CommercialBreak",
    "id": null,
    "errors": [
        {
            "errorCode": "CORE-00002",
            "description": "REFERENCE - type not found",
                    "data": [
                        "commercia"
                    ]
        }
    ]
}

Previously, when including an incorrect definition ID in the PUT /commercialBreak call, POST /commercialPlaylist call or GET /breakSchedule call, the error response would not mention that the ID was the problem. This issue has been fixed and now the ID is included in the response:

{
    "statusCode": "404",
    "message": "The specified resource does not exist.",
    "timestamp": "2021-09-16T08:19:11Z",
    "concept": "CommercialBreak",
    "id": null,
    "errors": [
        {
            "errorCode": "CORE-00404",
            "description": "The specified resource does not exist",
            "data": [
                "definitionId with id Promoz does not exist"
            ]
        }
    ]
}

Previously, when sending the GET call to retrieve the values of the media libraries, the response would only include the ID and name of the values. This was different to the response of the same call in the MAM API. Therefore, this issue has been fixed in the commercial API and the response includes all attributes of the values:

[
    {
        "id": "LinearLibrary",
        "name": "Linear library",
        "allowedMediaTypes": [
            "MAM File",
            "VHS"
        ],
        "hasUniqueMediaLabels": true
    }
]

Previously, when creating a media asset for a commercial in the POST /commercial, POST /commercialPlaylist and PUT /commercialBreak calls, it was possible to have behaviour that was not allowed in WHATS'ON.

If a value for the attribute kind was sent which cannot be broadcast (according to a setting in the drop-down list MM2MediaAssetKind), and the preferred attribute was set to true, the media asset would be created. It would be marked as preferred, but field Kind would be left empty, even though the value passed and was shown in the service. This is because in WHATS'ON, the media asset cannot be preferred and have a kind that is not suitable for broadcasting. Doing this in WHATS'ON shows an error message. This issue has now been fixed. The commercial is not created and the following response is returned:

{
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2021-06-30T10:47:13Z",
    "concept": "Commercial",
    "id": "be04be9e-9e34-4c4e-9397-1e57cff646f2",
    "errors": [
        {
            "errorCode": "CORE-00002",
            "description": "The kind of media asset cannot be used for broadcasting so you cannot set it as preferred",
            "data": [
                "NOT FOR AIR"
            ]
        }
    ]
}

This has also been fixed in the MAM API.

2021r2.000

API version: v1.0.0

Addition of Commercial integration API

To be able to support an interstitial integration using the business API, a commercial BAPI has been added. It will be used to exchange break schedules, commercials and commercial playlists between WHATS'ON and an ATS system.

More specifically, calls are created to support the following processes:

Send the break schedule from WHATS'ON to the external system via this BAPI.
Import the commercial playlist from the external system in WHATS'ON via this BAPI.
Import commercials from the external system in WHATS'ON via this BAPI (but not linked to the planning).

In WHATS'ON, the interstitial integration framework will be expanded to cope with the above scenarios (RN-4362).

The commercial integration API has the following calls:

GET /breakSchedule:
This call returns the break schedule for one complete broadcast day (for all time allocations that are part of the interstitial integration definition).

POST /commercialPlaylist:
This call allows the import, creation and linking of commercials and their media assets to the foreseen time allocations in the schedule.
It contains all commercials for a full broadcast day.
By executing the call, an interstitial schedule inbox will be created in WHATS'ON for the definition, channel and day as specified in the call.
Synchronisation of the schedule inbox with the WHATS’ON schedule remains as is.

PUT /commercialBreak:
This call allows to update the commercial breaks for a partial broadcast day or for single time allocations.

POST /commercial:
This call allows the creation of commercials and their linked media assets.

GET calls for drop-downs:
These drop-downs are needed to support the other calls.
- schedule versions
- time allocation types
- clash codes
- commercial types
- frame rates
- media asset statuses
- media asset kinds
- colour models
- video formats
- aspect ratios
- video statuses
- media libraries
- media types
- audio modes
- languages
- sounds
- audio statuses
- media asset templates